The Datafile PD-CD 1 Issue 2/PDCD-1 - Issue 02.iso/_utilities/utilities/004/_cliguard/!CLIGuard/!Help

Text File | 1994-09-24 | 15KB | 287 lines

CLI Guardian version 1.00
⌐ Sam Kington 23rd September 1994
This program is freeware, *not* public domain ù i.e., I retain copyright (see
öBoring legal messageò)

Terminology note
****************

   What the hell is the CLI, you may ask? And what do I mean by öCLIò?
      Å öCLIò stands for Command Line Interface.
      Å The CLI, under RISC OS, is the prompt you get for typing in ö*
        commandsò like *Modules, *Help Commands, *Set File$Type_FFF etc.
   You can get to the CLI in two ways:
      Å By öshelling outò to the CLI ù i.e. pressing F12.
      Å By using a task window ù i.e. pressing Ctrl-F12

What this program does
**********************

   CLI Guardian, as its name suggests, provides a way of avoiding shelling
out to the CLI, by making two important aspects of RISC OS desktop-friendly:
module handling, and *Help handling. It provides a list of modules, that you
can look at and sort in different ways, as well as doing various things to
the modules (killing them, re-initialising them, loading them into RAM etc.)
ù hopefully, anything you would do with modules that you had to use the CLI
before, you can do with CLI Guardian. It also allows you to view *Help
strings in a window, and to move, in a pseudo-hypertext fashion, between
references. (If youære not sure what I mean by this, read on).

   When you run CLI Guardian, it puts an icon on the icon bar, and starts
building its list of modules. The machine will multitask, but will run a bit
slower, until it ₧nishes doing all this.

   The program supports interactive help, so this documentation will only
cover the various aspects of the program that donæt ₧t in a small Help
message.

Modules
*******

   Clicking on CLI Guardianæs icon will open a list of modules to the left of
the screen. By default it will be a simple list of modules, in the standard
system order (i.e. ROM modules ₧rst, then RAM modules in the order they were
loaded), called in this program ösort by numberò. Clicking on any of the
modules will bring up a window with the various help options provided by the
module; clicking on those will bring up the appropriate help message (see
below). Unavailable modules (i.e. unplugged or dormant ROM modules) will be
displayed in grey or in italics, depending on whether you are using the
system font or not (see öChoicesò).

   Clicking MENU on the Modules window will bring up the main menu, where you
can set the display options, perform the standard operations on modules,
change the choices (colours, fonts, mouse clicks) and rescan the modules if
they get out of synch.

   CLI Guardian knows five different things about any particular module: its
öofficialò name (e.g. öColourTransò), its öfriendlyò name (e.g. öColour
Selectorò), its version number (e.g. 1.07 (15 Apr 1992), its status (e.g.
öROM (active)ò), and eventually a öspecialò ₧eld (often a copyright notice).
You can see these in the Info box off the öModuleò submenu, or by using
interactive help on the Modules window

   You can choose to display them in various combinations in the module
window, by using the öDisplayò submenu, so you could have a sparse display of
just official module names, or a big massive display with friendly name,
status, version number and special ₧eld. The only limitation is that they
must be in the order öname - status - version - specialò, and that you canæt
have both sorts of names at the same time ù mainly because theyære often not
very different at all.

   You can also sort the modules in various ways: sort by name (alphabetical
sort, using the official name), sort by number (standard sort, ROM modules
₧rst then RAM modules in the order they were loaded) or sort by version
number.

   CLI Guardian will ₧nd a list of modules quite quickly, but ₧nding out the
friendly name, version etc. and sorting the modules in various ways takes
longer, which is why it will do this in the background. This lets you get at
the machine quicker, but it has the side-effect that, if you are quick
enough, you will see that some of the options are temporarily unavailable
(greyed out). Also, if you have chosen to sort the modules by version (for
instance), they will be displayed sorted by number for quite a while, until
CLI Guardian ₧nishes sorting them by version number. This happens when you
₧rst start CLI Guardian, or when you rescan the modules. For this reason, you
are recommended to put CLI Guardian in your Boot sequence, near the end, so
it can work away when you ₧rst start up your machine and be ready when you
want to use it.

Help
****

   As mentioned above, clicking SELECT (by default) on the Modules window
will ₧nd all the help options supplied by the module ù help on commands,
con₧guration options, or other miscellaneous help ù and display them in a
window. Clicking on any of these options will in turn bring up a window with
the corresponding help text; clicking in that will try and ₧nd help using the
words in the line of text clicked on, and so on ad in₧nitum (or rather, until
you reach the limit of 16 windows).

   What is actually happening, is that when you click on a line of text, CLI
Guardian passes the line to *Help, and displays the result ù even if the
actual line wasnæt öintendedò to be clicked on like that. For instance, if
you click on öUtilityModuleò (or öMOS Utilitiesò if you have chosen öShow
friendly nameò), a rather large window will appear with a list of keywords,
divided into two sections, öCommandsò and öHelp onlyò. This is nothing more
than a nicer form of what you would get if you typed *Help UtilityModule from
the command line. However, if you clicked on öCon₧gureò, another window would
appear, with the heading öHelp on keyword Con₧gureò and a list of Con₧gure
keywords provided by modules. If you go down to the keywords provided by
öTerritory Mgrò, which should be something like öTerritory   DST   NODST
TimeZoneò, and click on that line, you will get a further window with four
sections, öHelp on keyword Territoryò, öHelp on keyword DSTò, etc., with the
appropriate help text.

   What you have here is a (rudimentary) form of hypertext. The best way to
₧nd out what you can do with it is to experiment ù for instance, clicking on
the heading öCommandsò will bring up a full list of commands.

   Clicking MENU on any window other than the Modules window will bring up a
smaller window, with three options, öHelpò, öCommandò and öSaveò. The ₧rst
two are equivalent to clicking Select or Adjust on the window; the third
brings up a Save box where you can save the contents of the windows to a ₧le
or an application.

   Choosing öHelp...ò from the icon bar menu will bring up a small dialogue
box where you can enter Help keywords; clicking öOKò will bring up a Help
window in the usual manner.

Commands
********

   Adjust-clicking (by default) on a viewer window (that is, any window other
than the Modules window) will bring up a dialogue box where you can enter a
*ácommand. The window has three main parts: the öCommandò writable ₧eld,
where you would enter the name of the actual command, four writable ₧elds in
the öArgumentsò section, where you can enter various arguments of the
command, and a set of icons.

   The window attempts to simulate both the CLI and the normal desktop way of
doing things, and at the same time separate arguments. When you ₧rst enter a
command, normally the window will either be blank or just have the name of a
command, without arguments; the cursor will be in the öCommandò writable
₧eld, after the command (if any). The arguments ₧elds will be greyed
out. Typing a space or pressing the Down arrow will move the cursor to the
next ₧eld, which will be ungreyed, until you get to the last ₧eld;
conversely, deleting the contents of an argument ₧eld will shift all other
arguments up, and possibly grey out the last argument ₧eld.

   In addition, the öHelpò button will provide help on the command (if there
isnæt any help, you might not have typed it correctly); if the command is
öSetò, öSetEvalò, öSetMacroò or öCon₧gureò, the öValueò button will show you
the current value of the variable or the con₧gure option you are about to
change. öOKò and öCancelò perform the expected actions: öCancelò stops the
whole thing, and öOKò runs the command, with the output going in a standard
CLI Guardian window. The only exception is for ödangerousò commands: things
like *Basic or *Debug that take over the machine, or things like *Map that
take a long time ù in other words commands that donæt return almost
instantaneously or depend on updating the screen regularly. There are only a
few of these, but if you do try and run one of these, CLI Guardian will
complain and refuse to run them.

   Finally, if you Adjust-click on a con₧guration option, CLI Guardian will
insert the command öCon₧gure <option>ò, where <option> should be replaced by
the name of the option, so öCon₧gureò would be in the command field and
ö<option>ò in the ₧rst of the argument ₧elds.

   Choosing öCommand...ò from the icon bar menu will also bring up the
window.

Choices
*******

   There are various ways you can customise CLI Guardian, notably by choosing
how it displays modules (see öModulesò for more details). Other choices can
be set with the öChoicesò submenu: colours, fonts and mouse actions.

   CLI Guardian uses three styles in its windows: normal style, heading style
and unavailable style. The normal style is applied to most text, the heading
style to things like öCommandsò or öHelp on keyword Con₧gureò, the
unavailable style to modules like öBBC Econetò or öJoystickò if you donæt
have the appropriate hardware. How these styles behave depends on whether you
are using outline fonts or not. If you are using the system font, CLI
Guardian uses colours to distinguish between styles (by default, red for
headings and grey for unavailable modules). If you are using outline fonts,
CLI Guardian wonæt use colours; partly because non-anti-aliased fonts look
ugly, and mainly because itæs a pain to do properly.

   The default fonts are Trinity.Medium for normal text,
Trinity.Medium.Italic for unavailable text, and Homerton.Bold for headings.
You canæt change the size because a) it would look silly, and b) itæs much
easier to assume a font is a certain size. 12 point is about the same size as
the System font, and as the point size of a font is a measure of its height
(more or less), the lines should be spaced out correctly (well, they are on
my machine, will all the fonts Iæve tried). You might get lines spilling over
the edge of the window, but I suspect that would be with strange fonts like
öFancyDressò. Obviously, Dingbats, MathGreek or other symbol fonts will look
rather silly...

   Finally, you can change the action of various mouse clicks, assigning
mouse clicks to mouse actions, by choosing öMouse clicks...ò from the
öChoicesò submenu; a window will appear, with the available commands and the
corresponding mouse click. For instance, if you click on the icon bar icon,
you can open the Modules window, enter a Help keyword, or enter a * command;
clicking on a window can search for help on the chosen line, use that line as
a command, bring up a save box or close the window. Obviously, with several
commands available and only two mouse buttons, you have to use Shift, Ctrl or
maybe even Alt if you want to be able to do all these things with the mouse,
so you can choose which ones are the most important to you.

   You can save these choices, cancel changes, and revert to default settings
with the menu.

Bug warning
***********

   Because I haven't had time to fully test this program, there may
occasionally be a few bugs left. I havenæt found anything that will bring
down the whole machine, and in normal use the program seems pretty stable;
itæs only when you try and do strange things that it falls down occasionally.

Boring legal message
********************

   This application is freeware, that is, it can be distributed freely as
long as only reasonable charges are made for media and distribution. I retain
copyright on all program code and documentation.

   This software is supplied öasáisò: I make no warranty, expressed or
implied, of the merchantability of this software or its ₧tness for any
particular purpose. In no circumstances shall I be liable for any damage,
loss of pro₧ts, or any indirect or consequential loss arising out of the use
of this software or inability to use this software, even if I have been
advised of the possibility of such loss.

   In other words, if your computer crashes, blows up, you lose all your work
etc. all because of CLI Guardian (unlikely I know), donæt blame me.

About all these strange foreign characters in this ₧le
*******************************************************

   OK, so if youære reading this on a PC or a Mac or another strange machine
like that, you may be wondering what all these strange ae things are. Well,
theyære quotes (sorry, there was another one), dashes, ligatures, etc.
Honest. But not on all machines...
   Basically, character sets are only standard up to character 127, which is
basically alphanumerics and a few standard punctuation marks. Foreign
characters, typographical oddities like quotes and ligatures, and other more
obscure symbols are önon-standardò, and each computer often has its own idea
of where they should go in the character set. So donæt worry: even if itæs
hard to read on your current machine, it wonæt be on an Acorn machine. It may
look slightly strange if youære using the System font, however.
   But why am I using these strange characters in the ₧rst place? Well,
theyære in the character set and they look nice in an outine font, and Iæve
written a program called Smart Quotes (sorry for the plug) that substitutes
these sort of characters automatically, and Iæve got it turned on at the
moment...

How to contact me
*****************

All bug-reports, suggestions, comments or indeed any feedback at all will be
welcomed. Hereæs how to get to me:

E-mail     : [e-mail], [e-mail] during term-time
             These should be OK until June 1996
             At Christmas, Easter and during the summer, you can get me at
             [e-mail], [e-mail] or [e-mail], in order
             of preference (that is, if mail bounces off one of these or I donæt
             answer within a week send to the next one).

Snail-mail : My term-time address, at least until June 1995, is:
             Sam Kington
             Flat 2/1
             44 Hotspur Street
             Glasgow G20 8NL
             SCOTLAND

             Again, a backup is the home address ù anything that goes here will get
             to me eventually.
             Sam Kington
             Merlhiot
             24420 Savignac les Eglises
             FRANCE

Term-time is October to June, with bits off at Christmas (3 weeks) and
Easter (4 weeks).